/****************************************************************************
 * Copyright 2009 Huascar A. Sanchez                                        *
 *                                                                          *
 * Licensed under the Apache License, Version 2.0 (the "License");          *
 * you may not use this file except in compliance with the License.         *
 * You may obtain a copy of the License at                                  *
 *                                                                          *
 *     http://www.apache.org/licenses/LICENSE-2.0                           *
 *                                                                          *
 * Unless required by applicable law or agreed to in writing, software      *
 * distributed under the License is distributed on an "AS IS" BASIS,        *
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. *
 * See the License for the specific language governing permissions and      *
 * limitations under the License.                                           *
 ****************************************************************************/
package com.gotobject.filter;

import com.gotobject.filter.builders.RestrictedFilteringBuilder;

/**
 * A very simple EDSL for filtering Iterable objects.
 * the main goal of this class is to alleviate the pain of using multiple if-else(..) checks, when iterating over a collection,
 * by means of building an expression which contains those multiple if-else(..), so that users will iterate
 * over those elements that satisfied the expression.
 * 
 * @author huascar.sanchez@gmail.com (Huascar A. Sanchez)
 */
public interface Filter {
    /**
     * records the thrown error and continue as usual. rather the throwing the
     * error immediately, the filter will thrown them when the user tries the access
     * the filtered elements from a collection.
     * @param cause error cause.
     */
    void addError(Throwable cause);

    /**
     * indicates the source from where the filter will extract a subset of elements.
     * @param source
     *      an {@link Iterable} object.
     * @param <T>
     *      bound type
     * @return
     *      a {@link RestrictedFilteringBuilder} object.
     */
    <T> RestrictedFilteringBuilder<T> from(Iterable<T> source);

}